 /*******************************************************************************
  * Copyright (c) 2000, 2005 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/

 package org.eclipse.update.core;

 import java.net.URL ;

 import org.eclipse.core.runtime.CoreException;
 import org.eclipse.core.runtime.IAdaptable;
 import org.eclipse.core.runtime.IProgressMonitor;
 import org.eclipse.update.core.model.InstallAbortedException;

 /**
  * Feature defines the packaging "container" for a group of related plug-ins,
  * plug-in fragments, and optionally non-plug-in files.
  * <p>
  * Features are treated purely as an installation and packaging construct.
  * They do not play a role during Eclipse plug-in execution.
  * They are simply an inclusive "manifest" of the plug-ins, fragments
  * and other files that make up that feature. If features are logically made
  * up of plug-ins from "sub-features", the top-level feature "manifest"
  * must be fully resolved at packaging time.
  * </p>
  * <p>
  * Clients may implement this interface. However, in most cases clients should
  * directly instantiate or subclass the provided implementation of this
  * interface.
  * </p>
  * <p>
  * <b>Note:</b> This class/interface is part of an interim API that is still under development and expected to
  * change significantly before reaching stability. It is being made available at this early stage to solicit feedback
  * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken
  * (repeatedly) as the API evolves.
  * </p>
  * @see org.eclipse.update.core.Feature
  * @since 2.0
  */
 public interface IFeature extends IAdaptable, IPlatformEnvironment {

     /**
      * Indicates a 'happy' feature
      * A feature is considered to be 'happy' in the context of a local site
      * if all the plug-ins referenced by the feature are installed on the site and no other
      * version of any of the plug-ins are installed on any other site of the local site.
      *
      * @see org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature)
      * @since 2.0
      */
     public static final int STATUS_HAPPY = 0;

     /**
      * Indicates a 'happy' feature
      * A feature is considered to be 'ambiguous' in the context of a local site
      * if all the plug-ins referenced by the feature are installed on the site and other
      * version of any of the plug-ins are installed on any other site of the local site.
      *
      * @see org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature)
      */
     public static final int STATUS_AMBIGUOUS = 1;
     
     /**
      * Indicates an 'unhappy' feature
      * A feature is considered to be 'unhappy' in the context of this site,
      * if some of the plug-ins referenced by the feature are not installed on this site.
      *
      * @see org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature)
      * @since 2.0
      */
     public static final int STATUS_UNHAPPY = 2;
     
     
     /**
      * Indicates a disable feature
      *
      * @see org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature)
      * @since 2.0.2
      */
     public static final int STATUS_DISABLED = -1;
         
     /**
      * Indicates the one-click update will search the
      * location of the nesting root feature.
      *
      * @since 2.0.1
      */
     public static final int SEARCH_LOCATION_DEFAULT = 0;

     /**
      * Indicates the one-click update will search the
      * location defined by the feature.
      *
      * @since 2.0.1
      */
     public static final int SEARCH_LOCATION_FEATURE = 1;

     /**
      * Indicates the one-click update will search both the
      * location of the nesting root feature and the
      * location defined by the feature.
      *
      * @since 2.0.1
      */
     public static final int SEARCH_LOCATION_BOTH = 2;

     
     /**
      * Returns the feature identifier.
      *
      * @return the feature identifier.
      * @since 2.0
      */
     public VersionedIdentifier getVersionedIdentifier();

     /**
      * Returns the site this feature is associated with.
      *
      * @return the site for this feature
      * @since 2.0
      */
     public ISite getSite();

     /**
      * Returns the displayable label of the feature.
      *
      * @return feature label, or <code>null</code>.
      * @since 2.0
      */
     public String getLabel();

     /**
      * Returns the feature URL.
      * This is the URL that was used to create the feature. The interpretation
      * of the URL is dependent on the concrete feature implementation. *
      * @return feature URL
      * @since 2.0
      */
     public URL getURL();

     /**
      * Returns an information entry referencing the location of the
      * feature update site. The update site can be accessed to obtain
      * feature updates for this feature.
      *
      * @return update site entry, or <code>null</code>.
      * @since 2.0
      */
     public IURLEntry getUpdateSiteEntry();

     /**
      * Return an array of information entries referencing locations of other
      * update sites. This mechanism can be used by features to distribute
      * location information about general update sites to clients.
      *
      * @return an array of site entries, or an empty array.
      * @since 2.0
      */
     public IURLEntry[] getDiscoverySiteEntries();

     /**
      * Returns a displayable label identifying the provider of this feature
      *
      * @return provider label, or <code>null</code>.
      * @since 2.0
      */
     public String getProvider();

     /**
      * Returns and optional custom install handler entry.
      *
      * @return install handler entry, or <code>null</code> if
      * none was specified
      * @since 2.0
      */
     public IInstallHandlerEntry getInstallHandlerEntry();

     /**
      * Returns the feature description.
      *
      * @return feature rescription, or <code>null</code>.
      * @since 2.0
      */
     public IURLEntry getDescription();

     /**
      * Returns the copyright information for the feature.
      *
      * @return copyright information, or <code>null</code>.
      * @since 2.0
      */
     public IURLEntry getCopyright();

     /**
      * Returns the license information for the feature.
      *
      * @return feature license, or <code>null</code>.
      * @since 2.0
      */
     public IURLEntry getLicense();

     /**
      * Return optional image for the feature.
      *
      * @return the URL pointing to the image, , or <code>null</code>.
      * @since 2.0
      */
     public URL getImage();

     /**
      * Return a list of plug-in dependencies for this feature. A plug-in
      * dependency is a reference to a plug-in required for feature execution
      * that is not packaged as part of the feature.
      * filtered by the operating system, windowing system and architecture system
      * set in <code>Sitemanager</code>
      *
      * @return the list of required plug-in dependencies, or an empty array.
      * @since 2.0
      */
     public IImport[] getImports();

     /**
      * Return a list of plug-in dependencies for this feature. A plug-in
      * dependency is a reference to a plug-in required for feature execution
      * that is not packaged as part of the feature.
      * No filtering occurs
      *
      * @return the list of required plug-in dependencies, or an empty array.
      * @since 2.1
      */
     public IImport[] getRawImports();
     
     /**
      * Return the identifier of the primary plugin associated to this feature
      * or <code>null</code> if the feature is not a primary feature.
      * If the primary plugin id is not specified and the feature is a primary
      * feature, returns the feature identifier.
      *
      * @return the identifier of the associated primary plugin or <code>null</code>
      * @since 2.1
      */
     public String getPrimaryPluginID();


     /**
      * Install the contents of this feature into the specified target feature.
      * All optional features will be installed
      *
      * @param targetFeature
      * @param verificationListener
      * @param monitor
      * @exception InstallAbortedException when the user cancels the install
      * @exception CoreException
      * @since 2.0
      */
     public IFeatureReference install(
         IFeature targetFeature,
         IVerificationListener verificationListener,
         IProgressMonitor monitor)
         throws InstallAbortedException,CoreException;

     /**
      * Install the contents of this feature into the specified target feature.
      * Only the listed optional features will be installed.
      *
      * @param targetFeature
      * @param optionalFeatures the optional features to be installed
      * @param verificationListener
      * @param monitor
      * @exception InstallAbortedException when the user cancels the install
      * @exception CoreException
      * @since 2.0.1
      */
     public IFeatureReference install(
         IFeature targetFeature,
         IFeatureReference[] optionalFeatures,
         IVerificationListener verificationListener,
         IProgressMonitor monitor)
         throws InstallAbortedException,CoreException;

     /**
      * Returns an array of feature references included by this feature
      * filtered by the operating system, windowing system and architecture system
      * set in <code>Sitemanager</code>
      *
      * @return an erray of feature references, or an empty array.
      * @since 2.0
      */
     public IIncludedFeatureReference[] getIncludedFeatureReferences() throws CoreException;

     /**
      * Returns an array of feature references included by this feature
      * No filtering occurs
      *
      * @return an erray of feature references, or an empty array.
      * @since 2.0
      */
     public IIncludedFeatureReference[] getRawIncludedFeatureReferences() throws CoreException;

     /**
      * Returns an array of plug-in entries referenced by this feature
      * filtered by the operating system, windowing system and architecture system
      * set in <code>Sitemanager</code>
      *
      * @return an erray of plug-in entries, or an empty array.
      * @since 2.0
      */
     public IPluginEntry[] getPluginEntries();

     /**
      * Returns an array of plug-in entries referenced by this feature
      * No filtering occurs
      *
      * @return an erray of plug-in entries, or an empty array.
      * @since 2.1
      */
     public IPluginEntry[] getRawPluginEntries();

     /**
      * Returns the count of referenced plug-in entries.
      *
      * @return plug-in entry count
      * @since 2.0
      */
     public int getPluginEntryCount();

     /**
      * Returns an array of non-plug-in entries referenced by this feature
      * filtered by the operating system, windowing system and architecture system
      * set in <code>Sitemanager</code>
      *
      * @return an erray of non-plug-in entries, or an empty array.
      * @since 2.0
      */
     public INonPluginEntry[] getNonPluginEntries();

     /**
      * Returns an array of non-plug-in entries referenced by this feature
      * No filtering occurs
      *
      * @return an erray of non-plug-in entries, or an empty array.
      * @since 2.1
      */
     public INonPluginEntry[] getRawNonPluginEntries();

     /**
      * Returns the count of referenced non-plug-in entries.
      *
      * @return non-plug-in entry count
      * @since 2.0
      */
     public int getNonPluginEntryCount();

     /**
      * Returns the download size of the feature, if it can be determined.
      *
      * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE
      * @return download size of the feature in KiloBytes, or an indication
      * the size could not be determined
      * @since 2.0
      */
     public long getDownloadSize();

     /**
      * Returns the install size of the feature, if it can be determined.
      *
      * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE
      * @return install size of the feature in KiloBytes, or an indication
      * the size could not be determined
      * @since 2.0
      */
     public long getInstallSize();

     /**
      * Indicates whether the feature can be used as a primary feature.
      *
      * @return <code>true</code> if this is a primary feature,
      * otherwise <code>false</code>
      * @since 2.0
      */
     public boolean isPrimary();
     
     /**
      * Indicates whether the feature must be processed alone during installation
      * and configuration. Features that are not exclusive can be installed in a
      * batch.
      *
      * @return <code>true</code> if feature requires exclusive processing,
      * <code>false</code> otherwise.
      * @since 2.1
      */
     public boolean isExclusive();

     /**
      * Returns an optional identifier of an application to be used when
      * starting up the platform with this feature as the primary feature.
      * The application identifier must represent a valid application registered
      * in the <code>org.eclipse.core.runtime.applications</code> extension point.
      *
      * @return application identifier, or <code>null</code>
      * @since 2.0
      */
     public String getApplication();
     
     /**
      * Returns an optional identifier of a colocation affinity feature.
      *
      * @return feature identifier, or <code>null</code>.
      * @since 2.0
      */
     public String getAffinityFeature();

     /**
      * Returns the content provider for this feature. A content provider
      * is an abstraction of each feature internal packaging structure.
      * It allows the feature content to be accessed in a standard way
      * regardless of the internal packaging. All concrete features
      * need to be able to return a content provider.
      *
      * @return feature content provider
      * @exception CoreException
      * @since 2.0
      */
     public IFeatureContentProvider getFeatureContentProvider()
         throws CoreException;

     /**
      * Returns the content consumer for this feature. A content consumer
      * is an abstraction of each feature internal packaging mechanism.
      * It allows content to be stored into a feature in a standard way
      * regardless of the packaging mechanism used. Only concrete features
      * that support storing need to implement a content consumer. The platform
      * implements at least one feature type supporting content consumer.
      * This is the feature type representing a locally-installed
      * feature.
      *
      * @return feature content consumer
      * @exception CoreException
      * @exception UnsupportedOperationException
      * @since 2.0
      */
     public IFeatureContentConsumer getFeatureContentConsumer()
         throws CoreException;

     /**
      * Sets the site for this feature. This is typically performed as part
      * of the feature creation operation. Once set, the site
      * should not be reset.
      *
      * @param site the site
      * @throws CoreException site for this feature is already set
      * @since 2.0
      */
     public void setSite(ISite site) throws CoreException;

     /**
      * Sets the content provider for this feature. This is typically
      * performed as part of the feature creation operation. Once set, the
      * provider should not be reset.
      *
      * @param featureContentProvider content provider
      * @since 2.0
      */
     public void setFeatureContentProvider(IFeatureContentProvider featureContentProvider);

     /**
      * Returns <code>true</code> if this feature is patching another feature,
      * <code>false</code> otherwise
      * @return boolean
      * @since 2.1
      */
     public boolean isPatch();


 }
